home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 September / Macworld (1998-09).dmg / Shareware World / Info / For Developers / MacZoop 1.8.3 / More Classes / Progress Dialog / ZProgress.h < prev    next >
Text File  |  1998-06-09  |  5KB  |  174 lines
  1. /*************************************************************************************************
  2. *
  3. *
  4. *            MacZoop - "the framework for the rest of us"         
  5. *
  6. *
  7. *
  8. *            ZProgress.h            -- a progress dialog
  9. *
  10. *
  11. *
  12. *
  13. *
  14. *            © 1996, Graham Cox
  15. *
  16. *
  17. *
  18. *
  19. *************************************************************************************************/
  20.  
  21. #pragma once
  22.  
  23. #ifndef __ZPROGRESS__
  24. #define    __ZPROGRESS__
  25.  
  26. #ifndef __ZDIALOG__
  27. #include    "ZDialog.h"
  28. #endif
  29.  
  30. // display types for the progress dialog- with "Cancel" button,
  31. // "Stop" button, or no button at all.
  32.  
  33. enum
  34. {
  35.     kCancelType,
  36.     kStopType,
  37.     kNoButton
  38. };
  39.  
  40. // display modes: normal or "stripey"
  41.  
  42. enum
  43. {
  44.     kProportionalProgress,
  45.     kIndeterminateProgress
  46. };
  47.  
  48. typedef short ProgType;
  49.  
  50. enum
  51. {
  52.     CLASS_ZProgress        = 'zprg'
  53. };
  54.  
  55. // progress class:
  56.  
  57. class    ZProgress : public ZDialog
  58. {
  59. protected:
  60.     short            theType;
  61.     long            max;
  62.     long            value;
  63.     long             createTime;
  64.     long             deferTime;
  65.     long            estTicksToFinish;
  66.     Rect            pRect;
  67.     Boolean            fAbort;
  68.     PixPatHandle    stripesPat;
  69.     ProgType        displayMode;
  70.     short            evtProcRatio;
  71.     short            evtProcCount;
  72.     ControlHandle    macOS8Control;    
  73.  
  74. public:
  75.  
  76.     ZProgress(     ZCommander* aBoss,
  77.                 const short dialogID,
  78.                 const long maxValue,
  79.                 const short pType = kCancelType,
  80.                 const ProgType aMode = kProportionalProgress );
  81.     ZProgress();
  82.     ~ZProgress();
  83.  
  84. // progress bar manipulation:
  85.     virtual Boolean        InformProgress( const long progressSoFar );            // update the bar    
  86.     virtual void        SetDelay( const short delayTicks );                    // set deferment delay
  87.     virtual void        SetMessage( const Str255& aMsg );                    // pass message directly
  88.     virtual void        SetMessage( const short resID, const short index);    // uses 'STR#' resources
  89.  
  90. // dialog overrides
  91.     virtual void        SetUp();                                            // override
  92.     virtual void        ClickItem( const short theItem );                    // override
  93.     virtual void        DrawUserItem( const short item );                    // override
  94.     virtual Boolean        Filter( EventRecord* theEvent );                    // override
  95.     virtual void        OutlineDefaultItem() {};                            // override
  96.     virtual void        Draw();                                                // override
  97.  
  98. // new: Change display mode on the fly
  99.     virtual void        SetMode( ProgType aMode );                        
  100.     inline    ProgType    GetMode() { return displayMode; };
  101.     inline    long        GetEstimatedCompletion() { return estTicksToFinish; };
  102.     
  103. // set the event processing ratio:
  104.  
  105.     virtual void        SetEventRatio( short aRatio ) { evtProcRatio = evtProcCount = aRatio; };
  106.  
  107. protected:
  108.     virtual void        CycleStripe();
  109.     virtual void        EstimateCompletionTime();
  110.     virtual void        UpdateTimeToComplete();
  111. };
  112.  
  113.  
  114.  
  115. // this class is blindingly easy to use. To keep the user informed of progress, simply
  116. // create the object (maybe as a stack object in your lengthy routine), passing the
  117. // maximum number of iterations of your function. Then call InformProgress with the
  118. // loop count within that function. This will update the bar, etc. If the user hits the
  119. // cancel/stop button, this function will return FALSE, indicating that you should abort
  120. // the function, or TRUE normally, to indicate that you should carry on. In addition to
  121. // this, you can pass -1 in the <maxValue> parameter to indicate that you don't know how
  122. // long the function will take, in which case the bar is drawn with a striped pattern that
  123. // is animated on each call to InformProgress. Finally, you can defer the appearance of the
  124. // dialog for a specified delay period- call SetDelay to set the deferment time in ticks. In
  125. // any case the dialog will only get shown when you call InformProgress. Note that this class
  126. // handles events, etc as normal, so your lengthy routine is effectively made to cooperate
  127. // with everything else. You need to be aware of this and that current ports, devices, etc may
  128. // not remain set across calls to InformProgress. SetMessage is used to set the additional
  129. // string the dialog displays above the bar- you do not need to use it. You can also use the
  130. // SetTitle method (inherited from ZWindow) to set the title of the progress dialog.
  131.  
  132. // change, 27/5/97- the display modes are now separate, so you can switch from proportional
  133. // to striped bar and back without affecting the setting of either. This is to make the class
  134. // more versatile, and compatible with the forthcoming Appearance Mgr control.
  135.  
  136. // change, 27/5/97. The limitation that you can have only one progress dialog up at once is
  137. // removed, since there may be a need for multiple ones in multi-threaded applications. To make
  138. // this work well, you might like to consider using a modeless dialog for your progress
  139. // indicators.
  140.  
  141.  
  142. // pass in <maxValue> for striped bar:
  143.  
  144. #define        _STRIPED_BAR    -1
  145.  
  146. // typical delay times in ticks:
  147.  
  148. #define        kTwoSeconds        120
  149. #define        kThreeSeconds    180
  150.  
  151. // standard dialog resource IDs and items
  152.  
  153. #define        kStdProgressResID    133
  154. #define        kTimeEstimateStrID    133
  155.  
  156. #define        kCancelButton        1
  157. #define        kBarItem            2
  158. #define        kMessageItem        3
  159. #define        kTimeRemLabel        4
  160. #define        kEstTimeDisplay        5
  161.  
  162. // pattern IDs used for bar ('ppat' resources)
  163.  
  164. #define        kStdBarPattern        129
  165. #define        kStdBackPattern        128
  166. #define        kStdStripedPattern    130
  167.  
  168. #define        kStopStringID        4
  169.  
  170. // errors:-
  171.  
  172. #define        kProgressAlreadyUpErr    222
  173.  
  174. #endif